BBS in a Box 7/BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso/Files/Tele/N-O/New Feature Files 11.cpt/New Features #2

Text File | 1989-10-10 | 20KB | 410 lines

New Features In White Knight 11 (file #2 of 2)
----------------------------------------------

This file continues the new features list that began in the first file.

Procedure Commands
------------------
• White Knight 11's Procedure language is upwardly compatible with Red
Ryder 10.3's.  A few small changes were necessary:
    1) STRIP now turns on/off the text transfer "Use filter" option.
    2) XKSTRIP now turns on the file transfer "Use filter" option.
    3) NOZAP ON now turns on IGNORE parity. NOZAP OFF now switches
       to NO parity.
    4) FASTDUMP has been eliminated as a Procedure command and has
       been implemented as an RCMD module (described later).
    5) TIMEDATE now uses the proper International date/time format.
    6) The MENUDOES command now allows up to 68 characters to be
       entered for each user menu command.

• The Procedure RUN command has been rewritten to support MultiFinder
and the launching of appications outside of the folder in which White
Knight resides.

• The number of string and numeric variables have been increased from 26
each to 234 of each.

• A plethora of new Procedure commands have been added.  I'm going to
document them in pretty much the same manner as in the version 10
manual, so refer to that if you have any questions about the syntax
descriptions.

str_exp = String Expression
str_con = String Constant
str_var = String Variable
num_exp = Numeric Expression
num_con = Numeric Constant
num_var = Numeric Variable
on_or_off_exp = On Or Off Expression
proc_cmd = Procedure Command

RECN str_exp
Similar to the RECA command, but it will always destroy an existing file
by the name contained in "str_exp" before starting the file capture.

RECF str_exp
This command is equivalent to choosing "Receive File Using Flash
Protocol" under the File menu.  The filename to be used as a default is
contained in "str_exp".

SUSPEND on_or_off_exp
"SUSPEND ON" is equivalent to checkmarking "File Capture Pause" under
the File menu.  "SUSPEND OFF" is equivalent to uncheckmarking "File
Capture Pause" under the File menu.

RECZ str_exp
This command is equivalent to choosing "Receive File Using ZMODEM
Protocol" under the File menu.  The filename to be used as a default is
contained in "str_exp".

SENDF str_exp
This command is equivalent to choosing "Send File Using Flash Protocol"
under the File menu.  The file to send is contained in "str_exp".

SENDZ str_exp
This command is equivalent to choosing "Send File Using ZMODEM Protocol"
under the File menu.  The file to send is contained in "str_exp".

FILTERT str_exp
FILTERF str_exp
FILTERP str_exp
These commands loads the Filter file specified in "str_exp".  "FILTERT"
loads the Filter file to the terminal emulation filter.  "FILTERF" loads
the Filter file to the file capture filter.  "FILTERP" loads the Filter
file to the file transfer filter.

VT102
Switches White Knight to VT102 emulation.

INITMODEM
This command is equivalent to choosing "Modem Initialize" under the
Service menu.

HANGUP
This command is equivalent to choosing "Modem Hang Up" under the Service
menu.

AUTOANSWER on_or_off_exp
"AUTOANSWER ON" is equivalent to choosing "Modem Auto-Answer" from under
the Service menu.  "AUTOANSWER OFF" is equivalent to choosing "Modem
Turn Off Auto-Answer" from under the Service menu.

NEST str_exp
This command is used to execute a second Procedure file from within a
Procedure file, and then later return to the same point in the first
Procedure file.  The Procedure file to execute is specified in
"str_exp".  In this way, separate Procedure files can be called as
subroutines similar to the way the "GOSUB" and "RETURN" Procedure
commands work with labels.  Procedures can be nested 6 levels deep, but
since a Modem Driver is essentially a nested Procedure file that can be
called at any given moment, you should take care not to nest your
Procedure files more than 5 levels deep.  Although the Procedure
Compiler will allow you to, you should never put a "NEST" command in an
"ALERT" statement, since the return point will be the command following
the "ALERT" statement, which is probably not what you want.

NESTEND
This command is used to return to the calling Procedure file in a file
executed with a "NEST" command.  If the Procedure file was not executed
with a "NEST" command, this command functions exactly like the "END"
command.

*
Any line in a Procedure file that begins with the asterisk character is
treated like a comment (the rest of the characters in the line are
ignored), but unlike those lines that start with a left parenthesis
character, these lines will actually be included in the executable
Procedure file.  These lines are mainly for use with the "TRACE"
command.

TRACE on_or_off_exp
"TRACE ON" turns on special trace mode.  "TRACE OFF" turns off special
trace mode.  The special trace mode is a bit different than the normal
trace mode provided by the "Monitor Procedure" menu choice and the
"LOUD" Procedure command.  Instead of showing each Procedure command as
it executes, the special trace mode shows the last line in the Procedure
file encountered which begins with a "*" character.  This can be used as
an aid in debugging to display messages such as:
"* I'm now in the 'Dial A Number' routine. *"
The special trace mode overrides the normal trace mode.

GETRECPATH str_var
This command puts the file transfer file destination pathname into the
string variable specified in "str_var".  The pathname does not conclude
with a colon character.  This command is useful for constructing full
filenames (by concatenating a colon character and then the desired
filename to this pathname) for use with the "RECX", "RECY", "RECK",
"RECZ", and "RECF" commands so that the file is saved in the folder
expected by the user.

SETRECPATH str_exp
This command sets the file transfer file destination pathname to the
pathname specified in "str_exp".  If the path is not valid, the root
level of the volume containing White Knight will be used.  The pathname
should not conclude with a colon character.

UNIQUE str_var
This command will create a filename based on the current date and time
and returns it in the string variable specified in "str_var".  To insure
uniqueness, you should put a "PAUSE 120" command between any two
"UNIQUE" commands

INBUFFER
This command will set the YES/NO flag to YES if there is at least one
byte in the serial port buffer waiting to be read.  If the serial port
buffer is empty, the YES/NO flag is set to NO.

FETCHBYTE str_var
This command sets the YES/NO flag like the "INBUFFER" command, but if a
byte is available, one byte is read and is copied (erasing any old
contents) to the string variable specified in "str_var".

BYTEVAL str_var,num_exp,num_var
This command gets the ASCII value of byte number "num_exp" contained in
"str_var" and places that value in "num_var".  If "num_exp" is larger
than the actual length of "str_var", the returned value is garbage and
shouldn't be used.

BYTEADD num_exp,str_var
This command concatenates a byte with the ASCII value specified in
"num_exp" to the end of the string variable specified in "str_var".

USEDRIVER str_exp
This command tells White Knight to load and use the Modem Driver file
specified in "str_exp".

WINDOW on_or_off_exp
This command shows (WINDOW ON) or hides (WINDOW OFF) the Macros Window.

BUTTON num_exp1,num_exp2,on_or_off_exp1,on_or_off_exp2
This command controls how a Macro Key is displayed in the Macros Status
Bar and Macros Window.  num_exp1 is the Macro Key Set Number (1, 2, or
3) containing the desired key, and num_exp2 is the Macro Key Number (0
through 9).  on_or_off_exp1 should be "ON" if you want the Macro Key to
be visible in the Macros Status Bar, or "OFF" if you want it to be
invisible. on_or_off_exp2 should be "ON" if you want the Macro Key to be
visible in the Macros Window or "OFF" if you want it to be invisible.

REDRAW
The BUTTON command does not redraw either the Macros Status Bar or the
Macros Window.  This is to provide a "cleaner" display when changing the
visibility and/or invisibility of groups of Macro Key buttons.
Therefore, the REDRAW command simply redraws the Macros Status Bar and
Macros Window.

NOBAR on_or_off_exp
The command "NOBAR ON" will hide the Status Bar.  The command "NOBAR
OFF" will force the Status Bar to be shown.  Notice that hiding the
Status Bar will also affect the "Monitor Procedure" feature, as well as
some Procedure commands (notably, QUIET, LOUD, TRACE, and SHOW@).
However, the Status Bar is required for the Host Mode (so the user can
exit the Host Mode).  In this case the "Hide Status Bar" menu choice
will be turned off automatically when Host Mode is entered.

SHUTDOWN
Closes White Knight similar to the QUIT command and then executes a
system Shut Down similar to if you chose "Shut Down" from under Finder's
"Special" menu.

USERPUT% num_exp,num_var
Used to write the contents of a numeric variable to a file opened with
the USEROPENO or USEROPENA command.  num_exp is the path number (1 or 2)
that was specified in the USEROPENO or USEROPENA command and num_var is
the numeric variable to write to that file.  Variables written with a
USERPUT% command _MUST_ be read back in with a USERGET% command!

USERGET% num_exp,num_var
Used to read a value into a numeric variable that was previously written
with a USERPUT% command from a file opened with a USEROPENI command.
num_exp contains the path number (1 or 2) specified in the USEROPENI
command, and num_var is the numeric variable to read the value into.
USERGET% should only be used to read in data that was saved with a
USERPUT% command.

USERPUT$ num_exp,str_var
Used to write the contents of a string variable to a file opened with
the USEROPENO or USEROPENA command.  num_exp is the path number (1 or 2)
that was specified in the USEROPENO or USEROPENA command and str_var is
the string variable to write to that file.  Variables written with a
USERPUT$ command _MUST_ be read back in with a USERGET$ command!

USERGET$ num_exp,str_var
Used to read a string of characters into a string variable that was
previously written with a USERPUT$ command from a file opened with a
USEROPENI command.  num_exp contains the path number (1 or 2) specified
in the USEROPENI command, and str_var is the string variable to read the
data into.  USERGET$ should only be used to read in data that was saved
with a USERPUT$ command.

The next group of Procedure commands deals with a new part of the White
Knight interface, the User Window.  Often times, it is desirable to hide
what's happening in the terminal window (via a "SCREEN OFF" Procedure
command) from the neophyte user, yet provide some sort of feedback that
progress is being made.  As you know, the various "QUERY" command dialog
boxes as well as "SHELL" command dialog boxes are all modal, which means
that all action behind the dialog box stops until the dialog box has
been clicked closed by the user.

The User Window is modeless, which means it will stay around until you
specifically get rid of it.  Additionally, it is updated automatically
when other windows overlap it and it does not affect the continued
execution of your Procedure file.  Finally, you can even control the
size and location of the User Window on the display screen.

UWOPEN0 num_exp1,num_exp2,num_exp3,num_exp4
CUWOPEN0 num_exp1,num_exp2,num_exp3,num_exp4
These commands use a dragable window with a title bar, but no go-away
box.  For both commands, num_exp1 is the top coordinate, num_exp2 is the
left coordinate, num_exp3 is the bottom coordinate, and num_exp4 is the
right coordinate of the window.  "UWOPEN0" uses these coordinates
exactly to size and position the window, so they should be given in
global screen coordinates.  "CUWOPEN0" uses the coordinates in a
relative manner to size the window, the actual postion of the window is
centered on the screen.  The window title is passed in the string
variable W$.  The text to appear in the window is passed in X$, Y$, and
Z$.  These strings are jammed right up against each other, so you'll
want to take care to include necessary spacing.  You can pass up to 132
characters in each string variable (taking care that the window size is
large enough to display all of the characters).

UWOPEN1 num_exp1,num_exp2,num_exp3,num_exp4
CUWOPEN1 num_exp1,num_exp2,num_exp3,numexp4
These commands are similar to "UWOPEN0" and "CUWOPEN1" (respectively),
except they produce a non-dragable window without a title bar and no
go-away box.  Therefore, W$ is not used by these commands.

UWOPEN2 num_exp1,num_exp2,num_exp3,num_exp4
CUWOPEN2 num_exp1,num_exp2,num_exp3,num_exp4
These commands are similar to "UWOPEN0" and "CUWOPEN1" (respectively),
except they include a go-away box in the title bar.

IF CLOSEUW proc_cmd
This command is used with dialog boxes created with "UWOPEN2" and
"CUWOPEN2" to monitor whether or not the user has clicked in the go-away
box.  When the user does this, the window is not closed, it's up to you
to do this explicitly.  If the go-away box has been clicked in before
this command has been executed, the Procedure command "proc_cmd" is
executed.  Otherwise, this command does nothing.

UWCLOSE
This command removes the User Window created by any of the "UWOPEN" and
"CUWOPEN" commands.  Please note that you can have only one User Window
open at any time.  If the User Window is not open when this command is
executed, it does nothing.  Please note that an open User Window will
survive even after a Procedure has ended or has been cancelled unless it
is explicitly closed using this command.  Therefore, if you want to give
the user the ability to abort the Procedure cleanly, you should use a
"UWOPEN2" or "CUWOPEN2", and when a click in the go-away box is
detected, branch to a closing routine.

UWUPDATE
If you want to change the contents of an open User Window, this command
is used to redisplay the text passed in the string variables X$, Y$, and
Z$. For User Windows created with "UWOPEN0", "CUWOPEN0", "UWOPEN2", and
"CUWOPEN2", it will also set the window title to the string passed in W$
(if the window has a title bar).

TOP num_var
This command is useful when used before a "UWOPEN0", "UWOPEN1", or
"UWOPEN2" command.  It returns the vertical global coordinate in the
numeric variable "num_var" of the bottom of the menu bar (which can be a
different size on different machines - don't take it for granted).  To
fit your window flush below the menu bar, you would add 19 to the number
returned by this command for "UWOPEN0" and "UWOPEN2" commands or add 8
to the number returned by this command for "UWOPEN1" commands.

There are a variety of new Procedure commands that deal only with RCMD
modules (discussed later) and Modem Drivers.  These will be documented
elsewhere.

RCMD Modules
An RCMD Module is a CODE resource that allows White Knight to be
extended beyond its basic capabilities.  Although RCMD's must be written
by software developers (and not beginners), they can be used by anyone.
Since the RCMD has access to a large number of White Knight's private
data, it can add a degree of intelligence and aesthetics not possible
through White Knight 11's Procedure language.

The possibilities with RCMD's seem endless, in only the short time that
I've taken to explore possible applications of them.  For instance, it's
possible to write (and one probably will be) an RCMD that can interface
to HyperCard's XFNC's and XCMD's!  There will be a number of sample
RCMD's distributed with White Knight 11.  Some, like AddLF, are useful
but sublime.  Other's, like ProcEdit, have a high degree of
sophistication and usefulness.  My goal was to explore a lot of
different avenues with these samples, and I'm sure they'll whet the
appetites of other developers as they have mine.  The samples include:

• AddLF - This module will add linefeeds after every carriage return in
a text file.  Useful if you'll be sending a file with a protocol to a
machine that requires linefeeds after carriage returns (example: IBM-
PC).

• FastDump - Replaces the FASTDUMP Procedure command in Red Ryder 10.3

• FolderBatch - This module prompts you to select a folder and then it
creates a Batch File (for sending with a protocol) containing the names
of every file in that folder.

• SetFile - This module allows you to view and/or edit all of the Finder
information (type, creator, and flags) for a specified file.

• Speak - This module allows you to interface with Macintalk in your
Procedures.

• TabFile - This module performs on a file what the "Copy Table" menu
choices does to selected text in the Terminal Window.

• QuickB - This module implements CompuServe's CIS-B and QuickB file
transfer protocols (for both sending and receiving) with the same File
Transfer Window White Knight 11 uses for its built-in protocols.

• ProcEdit - This module is a point-and-click Procedure Editor, somewhat
similar to MicroPhone's or SmartComm II's script editors.  Though meant
for beginners, it can be very useful for anyone.  It interfaces nicely
with White Knight 11, in that ProcEdit can direct a file to White Knight
to compile.  If an error occurs during compilation, White Knight will
branch back to ProcEdit, which will load that file and scroll to the
line containing the error for immediate correction.  ProcEdit implements
its own menus, and even supports desk accessories and background
operation under MultiFinder.

• Others - I have written several others that aren't appropriate for
mass distribution (they require more than beginner's skill to utilize),
and several of the beta testers have benn working on others.  The one's
that I do will be available through the FreeSoft RoundTable on GEnie and
through the mail in something I'm putting together called the "White
Knight Developer's Toolkit", which will also contain the information on
how to write RCMD's, Modem Drivers, and SHELL resources.  More details
about this will be in the White Knight manual.  My guess is that you'll
see literally dozens of these useful gizmos floating around in short
fashion.

The Surprise
------------
The very fact that this "new features" list is running over 40K long
should testify to the amount  of work that went into this new version.
However, it is still my feeling that this update is long overdue.

Some time back, I took advantage of my medical insurance and the
intensive care facilities of the local hospital to receive a donation of
four pints of blood after losing same to a rather large and pernicious
hole in my gut.  This little sidetrack caused me to lose over three
months of development time on White Knight 11.  Close to an additional
month was lost coming up with the new name and playing games with the
lawyers.  All in all, it's been a hell of an uphill fight to get this
thing out the door.

To thank my existing customers for their patience and continuing
support, and as an incentive to new customers, I've decided to include
at no extra cost a copy of my new product Okyto for a limited time.
This will be included in all updates and all new orders at least until
the end of 1989 (after that, who knows?).

I've been told by several people that this thing could easily sell for
anywhere from $60 to $100, and that I'm nuts for doing this.  But that
fits in well with my self-image, so what the heck.

As for what it does and whether it will be useful to you.  Well, that's
the surprise, you see.  I'm not talking.